Die Ultimative Software-P…i Collection 1996 & 1997/Die Ultimative Software-Pakete CD-ROM fur Atari Collection 1996 & 1997.iso/g/gnu_c/gccdoc.lzh/GCC-ST.STW

Atari Works Document | 1994-01-31 | 194.6 KB | 1,015 lines

Swiss 721
Cooper Black
Swiss 721
Cooper Black
How to install and use GCC on your Atari ST or TT
Copyright (C) 1991 Frank Ridderbusch
Author          : Frank Ridderbusch T35
Created On      : around 1 1/2 years ago
Last Modified By: Frank Ridderbusch
Last Modified On: Wed Sep 23 22:43:30 1992
Update Count    : 88
Status          : Beware, this version is not finished yet.
HISTORY
31-Jan-1994        Michael White
   Changed format to AtariWriter and text format.
20-Dec-1991        Frank Ridderbusch T35
    Last Modified: Fri Dec 20 11:34:04 1991
    Include chapter about C++ compiler driver options
20-Dec-1991        Frank Ridderbusch T35
    Last Modified: Fri Dec 20 08:58:56 1991
    Restructuring the utilities chapter. Various minor changes.
6-Dec-1991        Frank Ridderbusch T35
    Last Modified: Fri Dec  6 11:21:19 1991
    Run this file through ispell.
Introduction
************
This file documents the usage of the GNU C compiler on the Atari ST & TT computers and contains material from other copyrighted GNU manuals. The version of the C and C++ compiler, on which this manual is based are mainly 1.40 and 1.40.0 and some facts are from GCC 2.x. This manual does not yet cover GCC 2.x in it's complete beauty.
Copyright (C) 1988, 1989, 1990 Free Software Foundation, Inc.
          1990, 1991, 1992 Frank Ridderbusch
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU CC General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled ``GNU CC General Public License'' and this permission notice may be included in translations approved by the Free Software Foundation instead of in the original English.
Copyright 1988, 1989, 1990 Free Software Foundation, Inc.
Copyright 1990, 1991, 1992 Frank Ridderbusch
Introduction
This manual documents how to install and run the GNU C compiler on the Atari ST & TT computers.
Beware, this version is not finished yet. GCC 2.x is not yet completly covered, but since the majority of options is equal to GCC 1.x, this is not a real problem. Also GAS 1.92 is pending.
GNU CC GENERAL PUBLIC LICENSE
  The license agreements of most software companies keep you at the mercy of those companies.  By contrast, our general public license is intended to give everyone the right to share GNU CC.  To make sure that you get the rights we want you to have, we need to make restrictionsthat forbid anyone to deny you these rights or to ask you to surrender the rights.  Hence this license agreement.
Specifically, we want to make sure that you have the right to give away copies of GNU CC, that you receive source code or else can get it if you want it, that you can change GNU CC or use pieces of it in new free programs, and that you know you can do these things.
  To make sure that everyone has such rights, we have to forbid you to deprive anyone else of these rights.  For example, if you distribute copies of GNU CC, you must give the recipients all the rights that you have.  You must make sure that they, too, receive or can get the source code.  And you must tell them their rights.
  Also, for our own protection, we must make certain that everyone finds out that there is no warranty for GNU CC.  If GNU CC is modified by someone else and passed on, we want its recipients to know that what they have is not what we distributed, so that any problems introduced by others will not reflect on our reputation.
  Therefore we (Richard Stallman and the Free Software Foundation, Inc.) make the following terms which say what you must do to be allowed to distribute or change GNU CC.
COPYING POLICIES
You may copy and distribute verbatim copies of GNU CC source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy a valid copyright notice "Copyright Free Software Foundation, Inc." (or with whatever year is appropriate); keep intact the notices on all files that refer to this License Agreement and to the absence of any warranty; and give any other recipients of the GNU CC program a copy of this License Agreement along with the program.  You may charge a distribution fee for the physical act of transferring a copy.
You may modify your copy or copies of GNU CC or any portion of it, and copy and distribute such modifications under the terms of Paragraph 1 above, provided that you also do the following:
- cause the modified files to carry prominent notices stating that you changed the files and the date of any change; and
- cause the whole of any work that you distribute or publish, that in whole or in part contains or is a derivative of GNU CC or any part thereof, to be licensed at no charge to all third parties on terms identical to those contained in this License Agreement (except that you may choose to grant more extensive warranty protection to some or all third parties, at your option).
You may charge a distribution fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.
Mere aggregation of another unrelated program with this program (or its derivative) on a volume of a storage or distribution medium does not bring the other program under the scope of these terms.
You may copy and distribute GNU CC (or a portion or derivative of it, under Paragraph 2) in object code or executable form under the terms of Paragraphs 1 and 2 above provided that you also do one of the following:
- accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Paragraphs 1 and 2 above; or,
- accompany it with a written offer, valid for at least three years, to give any third party free (except for a nominal shipping charge) a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Paragraphs 1 and 2 above; or,
- accompany it with the information you received as to where the corresponding source code may be obtained.  (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form alone.)
For an executable file, complete source code means all the source code for all modules it contains; but, as a special exception, it need not include source code for modules which are standard libraries that accompany the operating system on which the executable file runs.
You may not copy, sublicense, distribute or transfer GNU CC except as expressly provided under this License Agreement.  Any attempt otherwise to copy, sublicense, distribute or transfer GNU CC is void and your rights to use the program under this License agreement shall be automatically terminated.  However, parties who have received computer software programs from you with this License Agreement willnot have their licenses terminated so long as such parties remain in full compliance.
If you wish to incorporate parts of GNU CC into other free programs whose distribution conditions are different, write to the Free Software Foundation at 675 Mass Ave, Cambridge, MA 02139.  We have not yet worked out a simple rule that can be stated here, but we will often permit this.  We will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software.
Your comments and suggestions about our licensing policies and our software are welcome!  Please contact the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, or call [phone].
NO WARRANTY
  BECAUSE GNU CC IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC, RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU CC "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF GNU CC IS WITH YOU.  SHOULD GNU CC PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL RICHARD M. STALLMAN, THE FREE SOFTWARE FOUNDATION, INC., AND/OR ANY OTHER PARTY WHO MAY MODIFY AND REDISTRIBUTE GNU CC AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS) GNU CC, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
Contributors to GNU CC
  In addition to Richard Stallman, several people have written parts of GNU CC.
- The idea of using RTL and some of the optimization ideas came from the U. of Arizona Portable Optimizer, written by Jack Davidson and Christopher Fraser.  See ``Register Allocation and Exhaustive Peephole Optimization'', Software Practice and Experience 14 (9), Sept. 1984, 857-866.
- Paul Rubin wrote most of the preprocessor.
- Leonard Tower wrote parts of the parser, RTL generator, RTL definitions, and of the Vax machine description.
- Ted Lemon wrote parts of the RTL reader and printer.
- Jim Wilson implemented loop strength reduction and some other loop optimizations.
- Nobuyuki Hikichi of Software Research Associates, Tokyo, contributed the support for the SONY NEWS machine.
- Charles LaBrec contributed the support for the Integrated Solutions 68020 system.
- Michael Tiemann of MCC wrote most of the description of the National Semiconductor 32000 series cpu.  He also wrote the code for inline function integration and for the SPARC cpu and Motorola 88000 cpu and part of the Sun FPA support.
- Jan Stein of the Chalmers Computer Society provided support for Genix, as well as part of the 32000 machine description.
- Randy Smith finished the Sun FPA support.
- Robert Brown implemented the support for Encore 32000 systems.
- David Kashtan of SRI adapted GNU CC to the Vomit-Making System.
- Alex Crain provided changes for the 3b1.
- Greg Satz and Chris Hanson assisted in making GNU CC work on HP-UX for the 9000 series 300.
- William Schelter did most of the work on the Intel 80386 support.
- Christopher Smith did the port for Convex machines.
- Paul Petersen wrote the machine description for the Alliant FX/8.
Aside from Michael Tiemann, who worked out the front end for GNU C++, and Richard Stallman, who worked out the back end, the following people (not including those who have made their contributions to GNU CC) should not go unmentioned.
- Doug Lea contributed the GNU C++ library.  This includes support for streams, obstacks, structured files, and other public service objects.
- Doug Schmidt has spent countless hours pursuing bugs in this compiler for sport.  He also wrote a perfect hash function generator in GNU C++ which was used to generate a replacement for the keyword recognizer in the lexical analyzer for both GNU CC and GNU C++.
- Marc Shapiro and Phillipe Gautron helped me implement features needed for the SOR distributed object management environment.
- Dirk Grunwald made the collect program usable under COFF.
- Angel Li adapted GNU C++ to VMS.
- Ron Cole provided additional help getting GNU C++ working on COFF-based systems.
- James Clark wrote a name demangler for the GNU C++ naming scheme, and integrated it with the linker.
- Michael Powell and Jim Mitchell helped design the GNU C++ exception handling mechanism.
The following people contributed specially to the version for the Atari ST & TT.
- John R. Dunning did the original port to the Atari ST.
- Jwahar R. Bammi improved the port and the libraries.
- Eric R. Smith wrote lots of code for the libraries.
- David Boyce ported G++ 1.39.1 and the libg++ 1.39.0 to the ST.
The following is a not necessarily complete list of people who either contributed code or bugfixes to the libraries: Michal Jaegermann, Scott Kolodzieski, Andreas Schwab, Frank Celler, Edgar Roeder, Kai-Uwe Bloem, Allan Pratt, Jens Tingleff, Thomas Koenig, Markus Nick. Apologies to those I forgot to mention.
Frank Ridderbusch compiled this manual specially for the Atari ST.
Introduction
  This manual documents how to install and run the GNU C compiler on the Atari ST & TT computers. It does not give an introduction in C or M68000 assembler. There is enough material on both subjects available. The user, who is familiar with a C compiler, that runs on a U**x system, should have no trouble at all to get GNU C running on the Atari ST. This manual was compiled from existing GNU manuals and various bits and pieces from John R. Dunning and Jwahar R. Bammi.
  The sections, which describe the compiler driver, the preprocessor and the G++ compiler driver are nearly verbatim copies of sections in the respective manuals. The original manuals (
Using and Porting GNU CC
The C Preprocessor
), were written by Richard M. Stallman and Michal D. Tieman (
User's Guide to GNU C++
). All of these three documents are copyright The Free Software Foundation. I modified these sections by removing material, which described features of GNU C for systems like Vaxen or Suns. To keep this manual reasonably compact, I extracted only the sections, which describe the supported command options (and predefined macros in case of the preprocessor). If the user is interested in the extensions and details, which are implemented in GNU C, he has to refer to the original manuals. Whether all described options are useful on the Atari has to be decided.
  The facts, which are presented in the assembler and utility sections are mostly derived from the sources of the respective programs (from a cross compiler kit by J. R. Bammi based on GNU C 1.31), which were available to me. Other facts were gathered by try and error. So, these sections may be a bit shaky.
  The first version of this manual was based on GCC 1.37.1. Then, GCC 1.40 and G++ 1.39.1 became available. The most noticeable differences were some new options ("-mint", "-G", "-z") and the extended symbol table format. In the beginning of 1992 the FSF released GCC 2.x. In this release GCC and G++ were merged into one large package. At the time of this writing the current version for the Atari is 2.2.2 with patchlevel 2. This manual doesn't cover all new command line options from GCC 2.2.2, but only the most valuable (in the authors opinion).
 The coverage of GCC 2.x is not yet complete. Also, GAS 1.92 is pending.
  Additionally two flavours of libraries are present. One version, which is now mostly maintained by J.R.Bammi, is for the ST running the native TOS operating system. The other flavour is maintained by E.R.Smith. This version is specially modified to support MiNT, the multitasking TOS extension, also from E.R.Smith. It is the aim of both maintainers to keep the libraries in sync as much as possible and possibly merge them together in the future.
(Changes are on the way to merge the two library sets into one. Jeff Jackson is currently writing a tsr (terminate and stay resident), that provides the UNIXMODE functionality for the extended file sytem at the system trap level aka the kernel. This extended file system functionality will then be removed from the library.)
  The best place to look for all the components (binaries and sources) is at the moment the Atari archive at terminator. The internet address for anonymous ftp is atari.archive.umich.edu (141.211.164.8).  Also a mail server called BART is active. Send a message with the word "help" in it to the address [e-mail] and BART will explain himself. The maintainers of this archive post a monthly message to the USENET newsgroup "comp.sys.atari.st", which explains, how to get things from the archive. The packaging of the files may be different as it is explained below.
  If you find any errors or typos in this manual or have any other comments, please let me know. My email address is:
[e-mail]
(Amerika (North & South))
[e-mail]
(Rest of world)
[e-mail]
(MausNet, a FIFO like network in Germany)
Installation
  There are basically three components, which make up a basic compiling system and which have to be installed. Each component is accessed via an environment variable. This three components are:
The executables
These are accessed via the normal "PATH" variable, by which all other programs are found and the variable "GCCEXEC".
The header files
The preprocessor accesses the header files via the variable "GNUINC". Any C++ header files are accessed via "GXXINC".
The libraries
The linker finds the startup file and the required libraries via the variable "GNULIB". The C++ library also belongs into this directory.
  All this stuff basically assumes that you're using a CLI (command line interpreter). A really good choice is "Gulam", which has very nice set of features, but there are quite a number of other CLI's around, which also might do the job. If want as much U**x feeling as possible, you might consider either "ash", which is compatible to the Bourne shell (ported by Stefan Neuhaus), or E.R.Smiths port of "tcsh" or Scott Kolodzieskis port of "BASH 1.12".
  Apart from the CLI you definitely should get yourself a "
make" utility. Again, good choices here are either the GNU "Make", which offers nearly the complete U**x make functionality on the ST or the "PDMAKE", which has only the core make functionality, but has on the other hand the advantage, that it requieres fewer system resources.
  I suggest the following directory structure on your disk partition:
\gnu\bin
for all executable programs. The compiler driver finds the executables in this directory by looking up the environment variable "GCCEXEC".
\gnu\lib
for the startup object modules and the libraries. The linker find the startup code and the libraries in this directory by looking up the variable "GNULIB".
\gnu\include
for the header files. The preprocessor finds the include file in this directory by looking up the environment variable "GNUINC".
  With earlier versions of GNU CC it was only allowed to put one path into the variables "GNULIB" and "GNUINC". GCC 1.37 and later allows you to put several paths into these variables, which are separated by either a "," or a ";". All the mentioned paths are searched in order to locate a specific file. However the startup module "crt0.o" is
 looked for in the first directory specified in "GNULIB". If the preprocessor can't find a include file in one of the directories specified by "GNUINC", it will also search the paths listed in "GNULIB".
Installing the Executables
  The compressed archive of the GNU C compiler binary distribution contains the 'common' executables of the GNU compiler. That means the compiler driver ("gcc.ttp"), the preprocessor ("gcc-cpp.ttp"), the main body ("gcc-cc1.ttp"), the assembler ("gcc-as.ttp") and the linker ("gcc-ld.ttp"), but depending from where you got your GCC the packaging might be different. The just mentioned programs are the absolute minimum. To be comfortable, you should get the following support programs:
gcc-ar.ttp
is the object library maintainer.
gdb.ttp
is the GNU debugger 2.6 modified for the Atari ST. John Dunning did the original port to the Atari. Since then Jwahar Bammi has extensively hacked it. GDB now uses DBX debugging information in the object files.  This requires an assembler with version 1.36 or greater.
sym-ld.ttp
creates the symbol file needed with GDB.
gcc-nm.ttp
prints the symbols of a GNU object library or an object file.
cnm.ttp
prints the symbol table of a GEMDOS executable.
fixstk.ttp
printstk.ttp
are used to modify and print the current stack size of an executable.
toglclr.ttp
TOS 1.4 users can toggle the clear above BSS to end of TPA flag for the GEMDOS loader. A newer version of "toglclr.ttp" also allows to toggle the loader bits, that were introduced with TOS versions 2.x and 3.x.
size68.ttp
This program list the values of the TEXT, DATA, and BSS sections of a ready to run executable.
xstrip.ttp
removes the symbol table from an executable.
  All this files should go in "\gnu\bin\" directory on your gnu disk. I personally keep my executables in the directory "e:\gnu\bin". You should than extend the search path of your CLI to include this directory or you move the compiler driver "gcc.ttp" and the files, which are
 invoked by "gcc.ttp" ("gcc.ttp" calls "gcc-cpp.ttp", "gcc-cc1.ttp", "gcc-as.ttp" and "gcc-ld.ttp") into the directory, where you keep your other executables. The next step is to actually define "GCCEXEC".  "gcc.ttp" uses this variable to locate the
preprocessor, compiler, assembler and the linker.  "GCCEXEC" contains a device/dir/partial-pathname, which not only consists of the directory, where the executables are kept, but also a common prefix, which is "gcc-". Assuming you also put the executables in the directory as described above, "GCCEXEC" would contain "e:\gnu\bin\gcc-". The value is the same, you would give the compiler driver with the "-B" option.
  Then you should define a variable called "TEMP". During compilation the output of the various intermediate stages is kept here.  The variable must
 contain a trailing backslash. If you have enough memory, "TEMP" should point to a ramdisk.
Installing the Libraries
  The next thing to do is to install the libraries. The distributed archive contains the following libraries (again, the packaging may vary):
crt0.o
gcrt0.o
are the startup object modules. The file "gcrt0.o" instead of "crt0.o" is used, if the sources files are compiled for execution profiling (the "-pg" option).
gnu.olb
gnu16.olb
are the standard libraries, the usual "libc" on other systems.
curses.olb
curses16.olb
are ports of the BSD curses.
gem.olb
gem16.olb
contain the Atari ST Aes/Vdi/FSM-GDOS bindings.
iio.olb
iio16.olb
contain the integer only "printf" and "scanf" functions.
pml.olb
pml16.olb
are the portable math libraries.
termcap.olb
termcap16.olb
are for the pure "termcap" support.
widget.olb
widget16.olb
are a small widget based on "curses"
  All these libraries go to a place described by the environment variable "GNULIB". Again this variable must
contain a trailing backslash. Staying with the above example, I've set the variable to "e:\gnu\lib". The libraries, which have a 16 in their names were compiled with the "-mshort" option. This makes integers the same size as shorts.
  If you like to write programs for MiNT, the TOS multitasking extension from E.R.Smith, you might consider to replace "gnu.olb", "gnu16.olb", "iio.olb" and "iio16.olb" with the libraries supplied by Eric Smith. The source and the binaries of these libraries can also be retrieved from the Atari archive at terminator. The files are "mntlib
.zoo for the sources and mntolb
.zoo for the binaries. They are found in the "mint" directory.
 is the version number, currently 20. Programs written with this libraries will also run under TOS, as long no MiNT specific features have been used. (See
The C-Compiler Driver
, for more info on compiling programs for MiNT (the "-mint" option))
  Another option is to have both sets of libraries installed. For this you have to rename the MiNT libraries according to the following scheme:
crt0.o ==> mcrt0.o
gcrt0.o ==> mgcrt0.o
gnu.olb ==> mint.olb
gnu16.olb ==> mint16.olb
  To select these files instead of the standard TOS versions and to activate the MiNT specific portions of the header files you have to include the "-mint" option in the "gcc.ttp" command line.
Installing the Header Files
  The last bit to install are the header files. They are contained in an archive of their own. The preprocessor now knows about the variable "GNUINC". Earlier version had to use the "-I  {prefix}" option, to get to the header files. According to the above examples, the files would be put in the directory "e:\gnu\include".  "GNUINC" has to be set accordingly.
  If you like to write programs for MiNT, apart from the libraries you also need the MiNT specific include files (also from the Atari archive). These are found in the archive "mntinc
.zoo in the "mint" directory.
 matches the version number of the library. (See
The C-Compiler Driver
 for more info on compiling programs for MiNT (the "-mint" option)).
  If you choose to have both sets of libraries installed you can keep the TOS specific header files since they are compatible with the MiNT ones.
Gulam Notes
  The programs, which come with the GCC distribution also understand filenames, which use the slash ("/") as a separator. When Gulam is your favorite CLI you will stick to the backslashes, since you otherwise lose the feature of command line completition.
  If you are using Gulam, you can define "aliases" to reach the executables under more common names.
Examples
alias cc e:\gnu\bin\gcc.ttp
alias ar e:\gnu\bin\gcc-ar.ttp
alias as e:\gnu\bin\gcc-as.ttp
alias ld e:\gnu\bin\gcc-ld.ttp
  Now you should be able to say "cc foo.c -o foo.ttp and the obvious thing should happen. If you still have trouble, compare your settings with the ones from the sample file "gulam.g". That should give you the right idea.
  One additional note to Gulam.  "crt0.o" is currently set up to understand the MWC/Atari convention of passing long command lines (except it doesn't look into the "_io_vector" part). Gulam users should set "env_style mw", if you want to give long args lines to "gcc.ttp".
  To summarize the above, here are the settings from my "gulam.g" initialization file. The usage of "UNIXMODE" environment variable is explained in the file "unixmode.doc", which is part of the library sources. The "GXXINC" variable is for G++.
set env_style mw
setenv TEMP i:
setenv PATH e:\gnu\bin;<your other search paths here>
setenv GCCEXEC e:\gnu\bin\gcc-
setenv GNULIB e:\gnu\lib
setenv GNUINC e:\gnu\include
setenv GXXINC e:\gnu\g++-inc
setenv UNIXMODE 'd/brG'
Installing G++
  For the G++ installation apply the same rules as for the GCC installation. The G++ compiler driver "g++.ttp" and the actual compiler "gcc-cc1+.ttp" belong in the same directory as the GCC executables. The preprocessor is shared between G++ and GCC. The library "g++.olb" goes into the same directory as all the other libraries. Since G++ has a complete set of include files of it's own, they all should be copied into the directory "\gnu\g++-inc". To let the preprocessor know, where it can find the include files, the variable "GXXINC" is used.
  The above is valid for G++ 1.xx. Since GCC and G++ were merge into one large package with version 2.x, there is no longer a special compiler driver for G++.  "gcc.ttp" determines from the file extension, whether the C or C++ compiler should be invoked. The file "gcc-cc1plus.ttp" is the actual C++ compiler. This file name is usually truncated to "gcc-cc1p.ttp" in the 8+3 TOS file system. What is said about the include files and the variable "GXXINC" is also true for G++ 2.x.
  To actually use G++, some requirements have to be fulfilled. You need the GCC include files and libraries with at least patch level 72.  Additionally the linker "gcc-ld.ttp" must have at least patch level 22.
  The library "g++.olb" is at the moment not 100% 16bit clean. That means, there is at the moment no version, which is compiled with the "-mshort" option.
Memory Requirements
  GCC loves memory. A lot. It loves to cons structures. Lots of them. Earlier versions probably won't run at all in less than 1 Meg; the version 1.36 of GCC will probably need 2 Meg. The "gcc-cc1.ttp" had 1/2 meg stack, and needs it for compiling large files with optimization turned on. Happily, it doesn't need all that stack for smaller files, or even big files without the "-O" option, so it should be feasible to make a compiler with a smaller stack (with "fixstk.ttp").
  GCC versions 1.37 and later uses another scheme for memory allocation. The programs "gcc-cpp.ttp" and "gcc-cc1.ttp" are setup for "_stksize == -1L".  This means, that an executable will use all available memory, doing mallocs from internal heap (as opposed to the system heap via "Malloc"), with "SP" initially set at the top, and heap starting just above the "BSS". So if the compiler runs out of memory, you probably need more memory (or get rid of accessories, tsr's etc and try).
  During my compilation of @TeX 3.1 on my ST, I found that the size of a source file is not main the limiting factor, but the size of a function. At that time my ST was equipped with 2.5 megs of memory. About 512 Kb was used for ramdisk, cache and some auto folder programs. With this configuration the maximum size of a function, which could be compiled, was about 14-20 KB depending on how much code was inlined. Additionally I was able to compile GCC 1.40 and GAS 1.38 on my ST, but for this I had nearly disable every program in the auto folder. So, with GCC 1.40 you're doing fine with at least 2.5 megs.
  With GCC 2.2 you definitly need more memory. The compiler executable itself is about 850 Kb in size. The C++ compiler is even larger (about 1.1 Mb). So, with GCC 2.2 you should have 4 Mb.
Controlling the C-Compiler Driver ("gcc.ttp")
  The GNU C compiler uses a command syntax much like the U**x C compiler. The "gcc.ttp" program accepts options and file names as operands.  Multiple single-letter options may
 be grouped: "-dr" is very different from "-d -r".
  When you invoke GNU CC, it normally does preprocessing, compilation, assembly and linking. File names which end in ".c" are taken as C source to be preprocessed and compiled; file names ending in ".i" are taken as preprocessor output to be compiled; compiler output files plus any input files with names ending in ".s" are assembled; then the resulting object files, plus any other input files, are linked together to produce an executable.
  Command options allow you to stop this process at an intermediatestage.
  For example, the "-c" option says not to run the linker. Then the output consists of object files output by the assembler.
  Other command options are passed on to one stage of processing. Some options control the preprocessor and others the compiler itself. Yet other options control the assembler and linker; these are not documented here, but you rarely need to use any of them.
  Here are the options to control the overall compilation process, including those that say whether to link, whether to assemble, and so on.
-o {file}
Place output in file {file}. This applies regardless to whatever sort of output is being produced, whether it be an executable file, an object file, an assembler file or preprocessed C code.
If "-o" is not specified, the default is to put an executable file in "a.out", the object file {source}.c in {source}.o", an assembler file in {source}.s, and preprocessed C on standard output.
Compile or assemble the source files, but do not link. Produce object files with names made by replacing ".c" or ".s" with ".o" at the end of the input file names. Do nothing at all for object files specified as input.
Compile into assembler code but do not assemble. The assembler output file name is made by replacing ".c" with ".s" at the end of the input file name.  Do nothing at all for assembler source files or object files specified as input.
Run only the C preprocessor. Preprocess all the C source files specified and output the results to standard output.
Compiler driver program prints the commands it executes as it runs the preprocessor, compiler proper, assembler and linker. Some of these are directed to print their own version numbers.
The executable is stripped from the DRI compatible or extended symbol table. Certain symbolic debuggers like "sid.prg" work with this symbol table. Also the programs "printstk.ttp" and "fixstk.ttp" (See
The Utilities
 for more info) lookup the symbol "_stksize in this table.
This option directs the linker to discard all local labels while creating the symbol table and write only those labels, which are marked global.
Instead of the standard DRI compatible symbol table, an extended symbol table is written, which allows symbol names to be up to 22 characters long. Most of the utility programs have been updated to work with this format. The most benefit you get with "gprof.ttp" and "adb" (the adb-like debugger, originally written for the Sozobon C compiler by Johann Rueg and Don Dugger and later improved by Michal Jaegermann (See
Debugging
 for additional info about debugging)).
-B {prefix}
The compiler driver program tries {prefix} as a prefix for each program it tries to run. These programs are "gcc-cpp.ttp", "gcc-cc1.ttp", "gcc-as.ttp" and "gcc-ld.ttp".
For each subprogram to be run, the compiler driver first tries the "-B" prefix, if any. If that name is not found, or if "-B" was not specified, the driver tries two standard prefixes, which are "/usr/lib/gcc-" and "/usr/local/lib/gcc-". If neither of those results in a file name that is found, the unmodified program name is searched for using the directories specified in your "PATH" environment variable.
You can get a similar result from the environment variable "GCCEXEC". If it is defined, its value is used as a prefix in the same way. If both the "-B" option and the "GCCEXEC" variable are present, the "-B" option is used first and the environment variable value second.
This option directs all output from "stderr" to the file "compile.err". So, all error messages and warnings, which are printed during a compile run are written to this file. The redirection is done by the compiler driver and is therefore only valid for those programs, which are subsequently invoked by "gcc.ttp". The "-z" option was introduced only very lately, so not every executable floating around might have it.
  These options control the details of C compilation itself.
-ansi
Support all ANSI standard C programs.
This turns off certain features of GNU C that are incompatible with ANSI C, such as the "asm", "inline" and "typeof" keywords, and predefined macros such as "unix" and "vax" that identify the type of system you are using. It also enables the undesirable and rarely used ANSI trigraph feature.
The "-ansi" option does not cause non-ANSI programs to be rejected gratuitously. For that, "-pedantic" is required in addition to "-ansi".
The macro "__STRICT_ANSI__" is predefined when the "-ansi" option is used.  Some header files may notice this macro and refrain from declaring certain functions or defining certain macros that the ANSI standard doesn't call for; this is to avoid interfering with any programs that might use these names for other things.
-traditional
Attempt to support some aspects of traditional C compilers. Specifically:
- All "extern" declarations take effect globally even if they are written inside of a function definition.  This includes implicit declarations of functions.
- The keywords "typeof", "inline", "signed", "const" and "volatile" are not recognized.
- Comparisons between pointers and integers are always allowed.
- Integer types "unsigned short" and "unsigned char" promote to "unsigned int".
- Out-of-range floating point literals are not an error.
- All automatic variables not declared "register" are preserved by "longjmp". Ordinarily, GNU C follows ANSI C: automatic variables not declared "volatile" may be clobbered.
- In the preprocessor, comments convert to nothing at all, rather than to a space. This allows traditional token concatenation.
- In the preprocessor, macro arguments are recognized within string constants in a macro definition (and their values are stringified, though without additional quote marks, when they appear in such a context). The preprocessor always considers a string constant to end at a newline.
- The predefined macro "__STDC__" is not defined when you use "-traditional", but "__GNUC__" is (since the GNU extensions which "__GNUC__" indicates are not affected by "-traditional").  If you need to write header files that work differently depending on whether "-traditional" is in use, by testing both of these predefined macros you can distinguish four situations: GNU C, traditional GNU C, other ANSI C compilers, and other old C compilers.
Optimize. Optimizing compilation takes somewhat more time, and a lot more memory for a large function. Without "-O", the compiler's goal is to reduce the cost of compilation and to make debugging produce the expected results. Statements are independent: if you stop the program with a breakpoint between statements, you can then assign a new value to any variable or change the program counter to any other statement in the function and get exactly the results you would expect from the source code.
Without "-O", only variables declared "register" are allocated in registers. The resulting compiled code is a little worse than produced by PCC without "-O".
With "-O", the compiler tries to reduce code size and execution time.Some of the "-f" options described below turn specific kinds of optimization on or off.
Produce debugging information in the operating system's native format (for DBX or SDB). GCC on the Atari produces the DBX debugging format. GDB also works with this debugging information.
Unlike most other C compilers, GNU CC allows you to use "-g" with "-O". The shortcuts taken by optimized code may occasionally produce surprising results: some variables you declared may not exist at all; flow of control may briefly move where you did not expect it; some statements may not be executed because they compute constant results or their values were already at hand; some statements may execute in different places because they were moved out of loops. Nevertheless it proves possible to debug optimized output. This makes it reasonable to use the optimizer for programs that might have bugs.
Produce debugging information in GDB's own format. This option is no longer supported. Do not use it.
Inhibit all warning messages.
Print extra warning messages for these events:
- An automatic variable is used without first being initialized.
These warnings are possible only in optimizing compilation, because they require data flow information that is computed only when optimizing.  They occur only for variables that are candidates for register allocation.  Therefore, they do not occur for a variable that is declared "volatile", or whose address is taken, or whose size is other than 1, 2, 4 or 8 bytes.  Also, they do not occur for structures, unions or arrays, even when they are in registers.
Note that there may be no warning about a variable that is used only to compute a value that itself is never used, because such computations may be deleted by the flow analysis pass before the warnings are printed.
These warnings are made optional because GNU CC is not smart enough to see all the reasons why the code might be correct despite appearing to have an error.  Here is one example of how this can happen:
  int x;
  switch (y)
    {
    case 1: x = 1;
      break;
    case 2: x = 4;
      break;
    case 3: x = 5;
    }
  foo (x);
If the value of "y" is always 1, 2 or 3, then "x" is always initialized, but GNU CC doesn't know this.  Here is another common case:
  int save_y;
  if (change_y) save_y = y, y = new_y;
 .........
  if (change_y) y = save_y;
This has no bug because "save_y" is used only if it is set.
Some spurious warnings can be avoided if you declare as "volatile" all the functions you use that never return.
- A nonvolatile automatic variable might be changed by a call to "longjmp".  These warnings as well are possible only in optimizing compilation.
- The compiler sees only the calls to "setjmp".  It cannot know where "longjmp" will be called; in fact, a signal handler could call it at any point in the code.  As a result, you may get a warning even when there is in fact no problem because "longjmp" cannot in fact be called at the place which would cause a problem.
- A function can return either with or without a value.  (Falling off the end of the function body is considered returning without a value.)  For example, this function would inspire such a warning:
foo (a)
  if (a > 0)
    return a;
Spurious warnings can occur because GNU CC does not realize that certain functions (including "abort" and "longjmp") will never return.
- An expression-statement contains no side effects.
In the future, other useful warnings may also be enabled by this option.
-Wimplicit
Warn whenever a function is implicitly declared.
-Wreturn-type
Warn whenever a function is defined with a return-type that defaults to "int".  Also warn about any "return" statement with no return-value in a function whose return-type is not "void".
-Wunused
Warn whenever a local variable is unused aside from its declaration, and whenever a function is declared static but never defined.
-Wswitch
Warn whenever a "switch" statement has an index of enumeral type and lacks a "case" for one or more of the named codes of that enumeration.  (The presence of a "default" label prevents this warning.)   "case" labels outside the enumeration range also provoke warnings when this option is used.
-Wcomment
Warn whenever a comment-start sequence "/*" appears in a comment.
-Wtrigraphs
Warn if any trigraphs are encountered (assuming they are enabled).
-Wall
All of the above "-W" options combined.  These are all the options which pertain to usage that we recommend avoiding and that we believe is easy to avoid, even in conjunction with macros.
The other "-W...." options below are not implied by "-Wall" because certain kinds of useful macros are almost impossible to write without causing those warnings.
-Wshadow
Warn whenever a local variable shadows another local variable.
-Wid-clash-{len}
Warn whenever two distinct identifiers match in the first {len} characters.  This may help you prepare a program that will compile with certain obsolete, brain-damaged compilers.
-Wpointer-arith
Warn about anything that depends on the "size of" a function type or of "void".  GNU C assigns these types a size of 1, for convenience in calculations with "void *" pointers and pointers to functions.
-Wcast-qual
Warn whenever a pointer is cast so as to remove a type qualifier from the target type.  For example, warn if a "const char *" is cast to an ordinary "char *".
-Wwrite-strings
Give string constants the type "const char[{length}]" so that copying the address of one into a "non-const char *" pointer will get a warning.  These warnings will help you find at compile time code that can try to write into a string constant, but only if you have been very careful about using "const" in declarations and prototypes.  Otherwise, it will just be a nuisance; this is why we did not make "-Wall" request these warnings.
Generate extra code to write profile information suitable for the analysis program "prof". This is useless on the Atari ST. Use "-pg" instead.
Generate extra code to write profile information suitable for the analysis program "gprof".
-l{library}
Search a standard list of directories for a library named {library}, which is actually a file named "$GNULIB\{library}.olb". The linker uses this file as if it had been specified precisely by name.
The directories searched include several standard system directories plus any that you specify with "-L".
Normally the files found this way are library files---archive files whose members are object files.  The linker handles an archive file by scanning through it for members which define symbols that have so far been referenced but not defined.  But if the file that is found is an ordinary object file, it is linked in the usual fashion.  The only difference between using an "-l" option and specifying a file name is that "-l" searches several directories.
-L{dir}
Add directory {dir} to the list of directories to be searched for {-l}.
-nostdlib
Don't use the standard system libraries and startup files when linking. Only the files you specify (plus "gnulib") will be passed to the linker.
-m{machinespec}
Machine-dependent option specifying something about the type of target machine. These options are defined by the macro "TARGET_SWITCHES" in the machine description. The default for the options is also defined by that macro, which enables you to change the defaults.
These are the "-m" options defined in the 68000 machine description:
-m68000
-mc68000
Generate output for a 68000. This is the default on the Atari ST.
-m68020
-mc68020
Generate output for a 68020 (rather than a 68000).
-m68881
Generate output containing 68881 instructions for floating point.
-msoft-float
Generate output containing library calls for floating point.
-mshort
Consider type "int" to be 16 bits wide, like "short int" and causes the macro "__MSHORT__" to be defined. Using this option also causes the library "{library}16.olb" to be linked. (Also
Predefined Macros
 for more info)
-mint
Compile for MiNT (MiNT is not TOS). The macro "__MINT__" is defined and the linker links with the mint library "-lmint"  before linking with the normal C library "-lgnu". Also, the linker uses the startup file "mcrt0.o" instead of the normal "crt0.o". If "-mshort" is also specified, then both the macros "__MSHORT__"  and "__MINT__" are defined and the linker links with "-lmint16 -lgnu16".
-mnobitfield
Do not use the bit-field instructions.  "-m68000 implies "-mnobitfield".
-mbitfield
Do use the bit-field instructions.  "-m68020" implies "-mbitfield".  This is the default if you use the unmodified sources.
-mrtd
Use a different function-calling convention, in which functions that take a fixed number of arguments return with the "rtd" instruction, which pops their arguments while returning. This saves one instruction in the caller since there is no need to pop the arguments there.
This calling convention is incompatible with the one normally used on U**x, so you cannot use it if you need to call libraries compiled with the U**x compiler.
Also, you must provide function prototypes for all functions that take variable numbers of arguments (including "printf"); otherwise incorrect code will be generated for calls to those functions.
In addition, seriously incorrect code will result if you call a function with too many arguments.  (Normally, extra arguments are harmlessly ignored.)
The "rtd" instruction is supported by the 68010 and 68020 processors, but not by the 68000.
-f{flag}
Specify machine-independent flags.  Most flags have both positive and negative forms; the negative form of "-ffoo" would be "-fno-foo".  In the table below, only one of the forms is listed---the one which is not the default.  You can figure out the other form by either removing "no-" or adding it.
-ffloat-store
Do not store floating-point variables in registers.  This prevents undesirable excess precision on machines such as the 68000 where the floating registers (of the 68881) keep more precision than a "double" is supposed to have.
For most programs, the excess precision does only good, but a few programs rely on the precise definition of IEEE floating point.  Use "-ffloat-store" for such programs.
-fno-asm
Do not recognize "asm", "inline" or "typeof" as a keyword.  These words may then be used as identifiers.
-fno-defer-pop
Always pop the arguments to each function call as soon as that function returns.  Normally the compiler (when optimizing) lets arguments accumulate on the stack for several function calls and pops them all at once.
-fstrength-reduce
Perform the optimizations of loop strength reduction and elimination of iteration variables.
-fcombine-regs
Allow the combine pass to combine an instruction that copies one register into another. This might or might not produce better code when used in addition to "-O". I am interested in hearing about the difference this makes. (Only GCC and G++ 1.40).
-fforce-mem
Force memory operands to be copied into registers before doing arithmetic on them.  This may produce better code by making all memory references potential common subexpressions.  When they are not common subexpressions, instruction combination should eliminate the separate register-load.  I am interested in hearing about the difference this makes.
-fforce-addr
Force memory address constants to be copied into registers before doing arithmetic on them. This may produce better code just as "-fforce-mem" may.
-fomit-frame-pointer
Don't keep the frame pointer in a register for functions that don't need one.  This avoids the instructions to save, set up and restore frame pointers; it also makes an extra register available in many functions.
It also makes debugging impossible.
On some machines, such as the Vax, this flag has no effect, because the standard calling sequence automatically handles the frame pointer and nothing is saved by pretending it doesn't exist.  The machine-description macro "FRAME_POINTER_REQUIRED" controls whether a target machine supports this flag.
-finline-functions
Integrate all simple functions into their callers. The compiler heuristically decides which functions are simple enough to be worth integrating in this way.
If all calls to a given function are integrated, and the function is declared "static", then the function is normally not output as assembler code in its own right.
-fcaller-saves
Enable values to be allocated in registers that will be clobbered by function calls, by emitting extra instructions to save and restore the registers around such calls.  Such allocation is done only when it seems to result in better code than would otherwise be produced.
This option is enabled by default on certain machines, usually those which have no call-preserved registers to use instead.
-fkeep-inline-functions
Even if all calls to a given function are integrated, and the function is declared "static", nevertheless output a separate run-time callable version of the function.
-fwritable-strings
Store string constants in the writable data segment and don't uniquize them.  This is for compatibility with old programs which assume they can write into string constants. Writing into string constants is a very bad idea; "constants" should be constant.
-fcond-mismatch
Allow conditional expressions with mismatched types in the second and third arguments. The value of such an expression is void.
-fno-function-cse
Do not put function addresses in registers; make each instruction that calls a constant function contain the function's address explicitly.
This option results in less efficient code, but some strange hacks that alter the assembler output may be confused by the optimizations performed when this option is not used.
-fvolatile
Consider all memory references through pointers to be volatile.
-fshared-data
Requests that the data and non-"const" variables of this compilation be shared data rather than private data.  The distinction makes sense only on certain operating systems, where shared data is shared between processes running the same program, while private data exists in one copy per process.
-funsigned-char
Let the type "char" be the unsigned, like "unsigned char".
Each kind of machine has a default for what "char" should be. It is either like "unsigned char" by default or like "signed char" by default.  (Actually, at present, the default is always signed.)
The type "char" is always a distinct type from either "signed char" or "unsigned char", even though its behavior is always just like one of those two.
Note that this is equivalent to "-fno-signed-char", which is the negative form of "-fsigned-char".
-fsigned-char
Let the type "char" be signed, like "signed char".
Note that this is equivalent to "-fno-unsigned-char", which is the negative form of "-funsigned-char".
-ffixed-{reg}
Treat the register named {reg} as a fixed register; generated code should never refer to it (except perhaps as a stack pointer, frame pointer or in some other fixed role).
{reg} must be the name of a register. The register names accepted are machine-specific and are defined in the "REGISTER_NAMES" macro in the machine description macro file.
This flag does not have a negative form, because it specifies a three-way choice.
-fcall-used-{reg}
Treat the register named {reg} as an allocatable register that is clobbered by function calls.  It may be allocated for temporaries or variables that do not live across a call. Functions compiled this way will not save and restore the register {reg}.
Use of this flag for a register that has a fixed pervasive role in the machine's execution model, such as the stack pointer or frame pointer, will produce disastrous results.
This flag does not have a negative form, because it specifies a three-way choice.
-fcall-saved-{reg}
Treat the register named {reg} as an allocatable register saved by functions. It may be allocated even for temporaries or variables that live across a call. Functions compiled this way will save and restore the register{reg} if they use it.
Use of this flag for a register that has a fixed pervasive role in the machine's execution model, such as the stack pointer or frame pointer, will produce disastrous results.
A different sort of disaster will result from the use of this flag for a register in which function values may be returned.
This flag does not have a negative form, because it specifies a three-way choice.
-pedantic
Issue all the warnings demanded by strict ANSI standard C; reject all programs that use forbidden extensions.
Valid ANSI standard C programs should compile properly with or without this option (though a rare few will require "-ansi"). However, without this option, certain GNU extensions and traditional C features are supported as well. With this option, they are rejected. There is no reason to
 this option; it exists only to satisfy pedants.
These options control the C preprocessor, which is run on each C source file before actual compilation. If you use the "-E" option, nothing is done except C preprocessing. Some of these options make sense only together with "-E" because they request preprocessor output that is not suitable for actual compilation.
Tell the preprocessor not to discard comments. Used with the "-E" option.
-I{dir}
Search directory {dir} for include files.
Any directories specified with "-I" options before the "-I-" option are searched only for the case of "#include "{file}""; they are not searched for "#include <{file}>".
If additional directories are specified with "-I" options after the "-I-", these directories are searched for all "#include" directives. (Ordinarily
 "-I" directories are used this way.)
In addition, the "-I-" option inhibits the use of the current directory as the first search directory for "#include "{file}"". Therefore, the current directory is searched only if it is requested explicitly with "-I.". Specifying both "-I-" and "-I." allows you to control precisely which directories are searched before the current one and which are searched after.
-nostdinc
Do not search the standard system directories for header files.  Only the directories you have specified with "-I" options (and the current directory, if appropriate) are searched.
Between "-nostdinc" and "-I-", you can eliminate all directories from the search path except those you specify.
Tell the preprocessor to output a rule suitable for "make" describing the dependencies of each source file.  For each source file, the preprocessor outputs one "make"-rule whose target is the object file name for that source file and whose dependencies are all the files "#include"d in it. This rule may be a single line or may be continued with "\"-newline if it is long.
"-M" implies "-E".
Like "-M" but the output mentions only the user-header filesincluded with "#include "{file}"". System header files included with "#include <@var{file}>" are omitted.
"-MM" implies "-E".
-D{macro}
Define macro {macro} with the empty string as its definition.
-D{macro}={defn}
Define macro {macro} as {defn}.
-U{macro}
Undefine macro {macro}.
Support ANSI C trigraphs. You don't want to know about this brain-damage. The "-ansi" option also has this effect.
Controlling the C++-Compiler Driver (g++.ttp)
  The GNU C++ compiler uses a command syntax much like the AT&T C++ compiler. The "g++.ttp" program accepts options and file names as operands.  Multiple single-letter options may
 be grouped: "-dr" is very different from "-d -r".
When you invoke GNU C++, it normally does preprocessing, compilation, assembly and linking.  File names which end in ".c", ".cc", or ".C" are taken as GNU C++ source to be preprocessed and compiled; compiler output files plus any input files with names ending in ".s" are assembled; then the resulting object files, plus any other input files, are linked together to produce an executable.
Unlike C++, there is no "-F" option.  This is because GNU C++ is a native-code C++ compiler, not a front-end pre-processor.  The advantages of this organization are faster compilation speed, better error-reporting capabilities, better opportunity for compiler optimization, and true source-level debuggability with the GDB debugger (version 3.4 or higher).
Command options allow you to stop this process at an intermediate stage. For example, the "-c" option says not to run the linker.  Then the output consists of object files output by the assembler.
Other command options are passed on to one stage.  Some options control the preprocessor and others the compiler itself.  Yet other options control the assembler and linker; these are not documented here because the GNU assembler and linker are not yet released.
Here are the options to control the overall compilation process, including those that say whether to link, whether to assemble, and so on. The options, which don't have any text, behave exactly as their GCC counterparts.
With GCC 2.x there is no independend compiler driver for C++.  "gcc.ttp" handles both cases. One major difference between "g++.ttp" from version 1.xx and "gcc.ttp" from version 2.x is, that you have to explicitly link with "g++.olb". Therefore when you compile C++ programs with GCC 2.x you alway have to include "-lg++" on the command line, when you create the final executable.
-o {file}
It is intended that the compiler driver of GNU C++ will invoke the appropriate translator (or series of translators) for a given source file.  Currently, the translators are selected on the basis of their file
extension.  So that one driver can be used for many different translators, it is important that these extensions be distinct.  It is strongly suggested that users become accustomed to using a ".cc" file extension for GNU C++ code, to distinguish it from the ".c" file extension already used for GNU CC code.
These options control the details of GNU C++ compilation itself.
-ansi
With this option enabled, differences between GNU C++ and AT&T C++ are also flagged.  Because the C++ language definition and the ANSI draft differ on the interpretation of syntactically identical constructs, it is unlikely that this flag could possibly be of any real use.  (For this reason, this flag is currently not fully implemented).
-traditional
The other aspects of "-traditional" are equivalent to GCC.
The predefined macro "__cplusplus" is defined to identify compilation for C++ 2.0.  C++ version 1.2 uses "c_plusplus" as its identifying macro.  Since GNU C++ implements version 2.0 semantics, the former is defined, while the latter is not.  The macro "__GNUG__" is also defined, so that features specific to GNU C++ can be used conditionally.
-Wimplicit
-Wreturn-type
-Wunused
-Wswitch
-Wcomment
-Wtrigraphs
-Wall
-Wshadow
-Wid-clash-{len}
-Wpointer-arith
-Wcast-qual
-Wwrite-strings
-l{library}
-L{dir}
-nostdlib
-m{machinespec}
-m68020
-mc68020
-m68000
-mc68000
-m68881
-msoft-float
-mshort
-mint
-mnobitfield
-mbitfield
-mrtd
-f{flag}
m -ffloat-store
-fno-asm
-fno-defer-pop
-fstrength-reduce
-fcombine-regs
-fforce-mem
-fforce-addr
-fomit-frame-pointer
-finline-functions
-fdefault-inline
If this option is enabled then member functions defined inside class scope are compiled inline by default,
, you don't need to add "inline" in front of the member function name.  By popular demand, this option is now the default.  To keep GNU C++ from inlining these member functions, specify "-fno-default-inline".
-fcaller-saves
-fkeep-inline-functions
-fwritable-strings
-fcond-mismatch
-fno-function-cse
-fvolatile
-fshared-data
-funsigned-char
-fsigned-char
-ffixed-{reg}
-fcall-used-{reg}
-fcall-saved-{reg}
-fstrict-prototype
Consider the declaration "int foo ();".  In C++, this means that the function "foo" takes no arguments.  In ANSI C, this is declared "int foo(void);".  With the flag "-fno-strict-prototype", declaring functions with no arguments is equivalent to declaring its argument list to be untyped, i.e., "int foo ();" is equivalent to
saying "int foo (...);".
-felide-constructors
Using this option instructs the compiler to be smarter about when it can elide constructors.  With out this flag, GNU C++ and cfront both generate effectively the same code for example:
A foo ();
A x (foo ());   // x is initialized by `foo ()', no ctor called here
A y = foo ();   // call to `foo ()' heads to temporary,
                // y is initialized from the temporary.
Note the difference!  With this flag, GNU C++ initializes `y' directly from the call to `foo ()' without going through a temporary.
-fall-virtual
When the "-fall-virtual" option is used, all member functions (except for constructor functions and new/delete member operators) declared in the same class with a "method-call" operator method have
entries made for them in the vtable for the given class.  In effect, all of these methods become "implicitly virtual."
This does
 mean that all calls to these methods will be made through the vtable.  There are some circumstances under which it is obvious that a call to a given virtual function can be made directly, and in these cases the calls still go direct.
The effect of making all methods of a class with a declared `operator->()()' implicitly virtual using "-fall-virtual" extends also to all non-constructor methods of any class derived from such a class.
-fthis-is-variable
The incorporation of user-defined free store management into C++ has made assignment to "this" an anachronism.  Therefore, by default GNU C++ treats the type of "this" in a member function of "class X" "X *const".  In other words, it is illegal to assign to "this" within a class member function.  However, for backwards compatibility, you can invoke the old behavior by using "-fthis-is-variable".
-fsave-memoized
-fmemoize-lookups
These flags are of use to get the compiler to compile programs faster using heuristics.  They are not on by default since they only do so about half the time.  They other half of the time programs compile more slowly (and take more memory).
The first time the compiler must build a call to a member function (or reference to a data member), it must (1) determine whether the class implements member functions of that name (2) resolve which member function to call (which involves figuring out what sorts of type conversions need to be made), and (3) check the visibility of the member function to the caller.  All of this adds up to slower compilation. Normally, the second time a call is made to that member function (or reference to that data member), it must go through the same lengthy process again.  This means that code like this
  cout << "This " << p << " has " << n << " legs.\n";
makes six passes through all three steps.  By using a software cache, a "hit" significantly reduces this cost.  Unfortunately, using the cache introduces another layer of mechanisms which must be implemented, and so incurrs its own overhead.  The "-fmemoize-lookups" enables the software cache.
Because access privileges (visibility) to members and member functions may differ from one function context to the next, may need to be flushed.  With the "-fmemoize-lookups" flag, the cache is flushed after every function that is compiled.  With the "-fsave-memoized"  flag, when the compiler determines that the context of the last function compiled would yield the same access privileges of the next function to compile, it preserves the cache.  This really helps when defining many member functions for the same class: with the exception of member functions which are friends of other classes, each member function has exactly the same access privileges as every other, and the cache need not be flushed.
-pedantic
Attempt to support strict ANSI standard C.  Since C++ invalidates a number of ANSI constructions, this switch is of dubious value.  Some attempt has been made to warn about non-standard C++ features, however, even this is of uncertain value, as there are two C++ standards currently in existence: the standard as documented by AT&T, and the standard as implemented by the AT&T C++ compiler.  Valid C++ programs should compile properly with or without this switch.  However, without this switch, certain useful or traditional constructs banned by the standard are supported.  With this switch, they are rejected.  There is no reason to use this switch; it exists only to satisfy curious pedants.
The options, which control the behaviour of the C preprocessor are the same as for GCC (See
The C-Compiler Driver
, last section).
The Preprocessor
Most often when you use the C preprocessor you will not have to invoke it explicitly: the C compiler will do so automatically. However, the preprocessor is sometimes useful individually.
Invoking the C Preprocessor
The C preprocessor expects two file names as arguments, "infile" and "outfile". The preprocessor reads "infile" together with any other files it specifies with "#include".  All the output generated by the combined input files is written in "outfile".
Either "infile" or "outfile" may be "-", which as "infile" means to read from standard input and as "outfile" means to write to standard output.  Also, if "outfile" or both file names are omitted, the standard output and standard input are used for the omitted file names.
Here is a table of command options accepted by the C preprocessor.  Most of them can also be given when compiling a C program; they are passed along automatically to the preprocessor when it is invoked by the compiler.
Inhibit generation of "#"-lines with line-number information in the output from the preprocessor. This might be useful when running the preprocessor on something that is not C code and will be sent to a program which might be confused by the "#"-lines
Do not discard comments: pass them through to the output file. Comments appearing in arguments of a macro call will be copied to the output before the expansion of the macro call.
Process ANSI standard trigraph sequences.  These are three-character sequences, all starting with "??", that are defined by ANSI C to stand for single characters.  For example, "??/" stands for "\", so "'??/n'" is a character constant for Newline. Strictly speaking, the GNU C preprocessor does not support all programs in ANSI Standard C unless "-T" is used, but if you ever notice the difference it will be with relief.
You don't want to know any more about trigraphs.
-pedantic
Issue warnings required by the ANSI C standard in certain cases such as when text other than a comment follows "#else" or "#endif".
-I {directory}
Add the directory {directory} to the end of the list of directories to be searched for header files.  This can be used to override a system header file, substituting your own version, since these directories are searched before the system header file directories.  If you use more than one "-I" option, the directories are scanned in left-to-right order; the standard system directories come after.
Any directories specified with "-I" options before the "-I-" option are searched only for the case of "#include "{file}""; they are not searched for "#include <{file}>".
If additional directories are specified with "-I" options after the "-I-", these directories are searched for all "#include" directives.
In addition, the "-I-" option inhibits the use of the current directory as the first search directory for "#include "{file}"".  Therefore, the current directory is searched only if it is requested explicitly with "-I.".  Specifying both "-I-" and "-I." allows you to control precisely which directories are searched before the current one and which are searched after.
-nostdinc
Do not search the standard system directories for header files.  Only the directories you have specified with "-I" options (and the current directory, if appropriate) are searched.
-D {name}
Predefine {name} as a macro, with definition "1".
-D {name}={definition}
Predefine {name} as a macro, with definition{definition}.  There are no restrictions on the contents of {definition}, but if you are invoking the preprocessor from a shell or shell-like program you may need to use the shell's quoting syntax to protect characters such as spaces that have a meaning in the shell syntax.
-U {name}
Do not predefine {name}. If both "-U" and "-D" are specified for one name, the "-U" beats the "-D" and the name is not predefined.
-undef
Do not predefine any nonstandard macros.
Instead of outputting the result of preprocessing, output a list of "#define" commands for all the macros defined during the execution of the preprocessor.
Instead of outputting the result of preprocessing, output a rule suitable for "make" describing the dependencies of the main source file.  The preprocessor outputs one "make" rule containing the object file name for that source file, a colon, and the names of all the included files.  If there are many included files then the rule is split into several lines using "\"-newline.
This feature is used in automatic updating of makefiles.
Like "-M" but mention only the files included with "#include "{file}"".  System header files included with "#include <{file}>" are omitted.
-i {file}
Process {file} as input, discarding the resulting output, before processing the regular input file.  Because the output generated from {file} is discarded, the only effect of "-i {file}" is to make the macros defined in {file} available for use in the main input.
Predefined Macros
The standard predefined macros are available with the same meanings regardless of the machine or operating system on which you are using GNU C.  Their names all start and end with double underscores.  Those preceding "__GNUC__" in this table are standardized by ANSI C; the rest are GNU C extensions.
__FILE__
This macro expands to the name of the current input file, in the form of a C string constant.
__LINE__
This macro expands to the current input line number, in the form of a decimal integer constant.  While we call it a predefined macro, it's a pretty strange macro, since its "definition" changes with each new line of source code.
This and "__FILE__" are useful in generating an error message to report an inconsistency detected by the program; the message can state the source line at which the inconsistency was detected. For example,
fprintf (stderr,
     "Internal error: negative string length "
         "%d at %s, line %d.",
         length, __FILE__, __LINE__);
A "#include" command changes the expansions of "__FILE__" and "__LINE__" to correspond to the included file.  At the end of that file, when processing resumes on the input file that contained the "#include" command, the expansions of "__FILE__" and "__LINE__" revert to the values they had before the "#include" (but "__LINE__" is then incremented by one as processing moves to the line after the "#include").
The expansions of both "__FILE__" and "__LINE__" are altered if a "#line" command is used.
__DATE__
This macro expands to a string constant that describes the date on which the preprocessor is being run.  The string constant contains eleven characters and looks like "Jan 29 1987" or "Apr 1 1905".
__TIME__
This macro expands to a string constant that describes the time at which the preprocessor is being run.  The string constant contains eight characters and looks like "23:59:01".
__STDC__
This macro expands to the constant 1, to signify that this is ANSI Standard C. (Whether that is actually true depends on what C compiler will operate on the output from the preprocessor.)
__GNUC__
This macro is defined if and only if this is GNU C.  This macro is defined only when the entire GNU C compiler is in use; if you invoke the preprocessor directly, "__GNUC__" is undefined.
__STRICT_ANSI__
This macro is defined if and only if the "-ansi" switch was specified when GNU C was invoked.  Its definition is the null string. This macro exists primarily to direct certain GNU header files not to define certain traditional U**x constructs which are incompatible with ANSI C.
__VERSION__
This macro expands to a string which describes the version number of GNU C.  The string is normally a sequence of decimal numbers separated by periods, such as "1.18".  The only reasonable use of this macro is to incorporate it into a string constant.
 __OPTIMIZE__
This macro is defined in optimizing compilations.  It causes certain GNU header files to define alternative macro definitions for some system library functions.  It is unwise to refer to or test the definition of this macro unless you make very sure that programs will execute with the same effect regardless.
__CHAR_UNSIGNED__
This macro is defined if and only if the data type "char" is unsigned on the target machine. It exists to cause the standard header file "limit.h" to work correctly.  It is bad practice to refer to this macro yourself; instead, refer to the standard macros defined in "limit.h".
__MSHORT__
This macro is defined, if "gcc.ttp" is invoked with the "-mshort" option, which causes integers to be 16 bit. Please carefully examine the prototypes in the "#include <>" headers for types before using "-mshort".
__MINT__
This macros is defined, if "gcc.ttp" is invoked with the "-mint" option. This macros activates some portions of the header files, which are MiNT specific. Up to version 8 of the MiNT libraries and headers the header files of J.R.Bammi's libraries are compatible with the ones from Eric Smith's library. Therefore if you were writing programs for MiNT you could stick to Bammi's headers and use the "-mint" option. I don't know, if header files are still compatible with version 10 of the MiNT libraries.
Apart from the above listed macros, there are usually some more to indicate what type of system and machine is in use. For example "unix" is normally defined on all U**x systems. Other macros describe more or less the type of CPU the system runs on. GNU CC for the Atari ST has the following macros predefined.
atarist
Please keep in mind, that these macros are only defined, if the preprocessor is invoked from the compiler driver "gcc.ttp".
These predefined symbols are not only nonstandard, they are contrary to the ANSI standard because their names do not start with underscores.  However, the GNU C preprocessor would be useless if it did not predefine the same names that are normally predefined on the system and machine you are using.  Even system header files check the predefined names and will generate incorrect declarations if they do not find the names that are expected.
The "-ansi" option which requests complete support for ANSI C inhibits the definition of these predefined symbols.
Generating Dependency Information
  The preprocessor has a not so well known feature, which lets you generate dependency information for makefiles and write these dependencies directly into a file.
  You already know about the options "-M" and "-MM" for the compiler driver and the preprocessor (See
The Preprocessor
 for more info).
DEPENDENCIES_OUTPUT
SUNPRO_DEPENDENCIES
The GNU Assembler (GAS)
  Most of the time you will be programming in C. But there may certain situations, where it is feasible to write in assembler. Time is usually a main reason to dive into assembler programming, when you have to squeeze the last redundant machine cycle out of your routine, to meet certain time limits. Another reason might be, that you have to do very low level stuff like fiddling with bits in the registers of a peripheral chip. An example for low level stuff is the startup module "crt0.o", which is written in assembler.
  If you already have some experience in assembler programming, you might miss the feature of creating macros. This is not really a lack given the fact, that the assembler originated from an U**x environment.  Under this operating system there is a tools for nearly every purpose.  If you were in the need of an extensive macros facility, you would use the M4 macro processor. A GNU version of the M4 macro processor exists. It should be no problem to port it to the Atari with GCC. For some macro processing tasks you just as well use the C preprocessor. What I personally miss is the ability to produce a listing, but this will be fixed with GAS 1.92.
  One command line option was introduced only very lately. The changes for the option "-m68040" were part of update 20, which Bammi released around end of April 1992. The assembler identifies itself, when invoked with the "-v" option with the string "GNU assembler version 1.38 atariST PatchLevel 2".
Invoking the Assembler
"gcc-as.ttp" supports the following command line options. The output is written to "a.out" by default.
assembles the debugging information the C compiler included into the output. Without this flag the debugging information is otherwise discarded.
Normally all labels, that start with a "L" are discarded and don't show up as symbols in the object code module. They are local to that assembler module. If the "-L" option is given, all local labels will be included in the object code module.
keep externals to 2 bit offset.
-m68000
-m68010
-m68020
-m68040
These options modify the behavior of assembler in respect of the used CPU. The M68020, for example, allows relative branches with 32-bit offset.
-o{filename}
writes the output to {filename} instead of{a.out}.
The information, which normally would be assembled into the data section of the program, is moved into the text section.
displays the version of the assembler.
suppresses all warning messages.
Syntax
The assembler uses a slightly modified syntax from the one you might  know from other 68000 assemblers, which use the original Motorola syntax. The next sections trys to describe the syntax, GAS uses.
The most obvious differences are the missing "." and the usage of the at sign ("@"). The original Motorola syntax uses the "." to separate the size modifier ("b", "w", "l") from the main instruction. In Motorola syntax one would write "move.l #1,d0" to move a long word with value 1 into register "d0". With GAS you simple write "movel #1,d0". The "@" is used to mark an indirection equivalent to the Motorola parentheses. To move a long word of value 1 to the location addressed by "a0", you have to write "movel #1,a0@". The equivalent instruction expressed in Motorola "move.l #1,(a0)". The "#" indicates immediate data in both cases.
Register Names and Addressing Modes
The register mnemonics are "d0..d7" for the data registers and "a0..a7" or "sp" for address register and the stack pointer.  "pc" is the program counter, "sr" the status register, "ccr" the condition code register and "usp" the user stack  pointer.
The following table shows the operands GAS can parse. (The first part part describe the used abbreviations. The second part show the addressing modes with a equivalent C expression.)
numb:
a 8 bit number
numw:
a 16 bit number
numl:
a 32 bit number
dreg:
data register 0..7
address or data register
areg:
address register 0..7
address register or PC
a 16 or 32 bit number
num2:
a 16 or 32 bit number
"w" or "l"; if omitted, "l" is  assumed.
scale:
1 2 4 or 8. If omitted, 1 is assumed.
Addressing Modes
Immediate Data
#num                          --> NUM
Data- or Address Register Direct
dreg                          --> dreg
areg                          --> areg
Address Register Indirect
areg@                        --> *(areg)
Address Register Indirect with Postincrement or Predecrement
areg@+                        --> *(areg++)
areg@-                        --> *(--areg)
Address Register (or PC) Indirect with Displacement
apc@(numw)                    --> *(apc+numw)
Address Register (or PC) Indirect with Index (8-Bit Displacement)
(M68020 only)
apc@(num,reg:sz:scale)        --> *(apc+num+reg*scale)
apc@(reg:sz:scale)            --> same, with num=0
Memory Indirect Postindexed
(M68020 only)
apc@(num)@(num2,reg:sz:scale) --> *(*(apc+num)+num2+reg*scale)
apc@(num)@(reg:sz:scale)      --> same, with num2=0
apc@(num)@(num2)              --> *(*(apc+num)+num2)
                                 (previous mode without an index reg)
Memory Indirect Preindexed
(M68020 only)
apc@(num,reg:sz:scale)@(num2) --> *(*(apc+num+reg*scale)+num2)
apc@(reg:sz:scale)@(num2)     --> same, with num=0
Absolute Address
num:sz                        --> *(num)
num                           --> *(num) (sz L assumed)
Labels and Identifiers
User defined identifiers are basically defined by the same rules as C identifier. They may contain the digits 0..9, the letters A..z and the underscore and must not start with a digit. Identifier, which end with a ":" are labels. A special form of labels starts with a "L" or consists of only a digit. Both types are local labels, which disappear, when the assembly is complete (unless the "-L" option was specified). They can't be used to resolve external references.  The "L" type label are referenced by their name, just as any other
label. The digit type labels form a special kind of local labels. You might also call them temporary labels. They are especially useful when you have to create small loops, which poll a peripheral or fill a memory area. They are referenced by appending either a "f", for a forward reference, or a "b", for a backward reference, to the digit. Lets look at the following example, which is used to split a memory area starting at "0x80000". All data on an even addresses is copied to the area starting at "0x70000"; all data from odd addresses goes to the area starting at "0x78000".
start:
        lea     0x80000,a0
        lea     0x70000,a1
        lea     0x78000,a2
        movel   #0x7fff,d5
0:                              | label "0" is defined
        moveb   a0@+,a1@+
        moveb   a0@+,a2@+
        dbra    d5,0b           | reference of label "0"
         ......
The label "0" is referenced 3 lines later by "0b", since the reference is backward. You can use the label "0" again at a later time to construct more such loops. Since this temporary labels are restricted to one digit in length, you can only build constructs, which use 10 temporary labels at the same time.
Comments
The above example also shows, that comments start with a "|".  "#" is also used to mark a comments. The C compiler and the preprocessor generate lines, that start with a "#".
Numerical and String Constants
Numerical values are given the same way as in a C programs. By default number are taken to be decimal. A leading "0" denotes an octal and a "0x" a hexadecimal value. Floating point numbers start with a "0f". The optional exponent starts with a "e" or "E".
String constants are equivalent to C defined. They are enclosed in " " ". Some special character constants are defined by "\" and a following letter. These characters are possible:
Backspace, Code 0x08
Tab, Code 0x09
Line Feed, Code 0x0a
Form Feed, Code 0x0c
Carriage Return, Code 0x0d
Backslash itself
Double Quote itself
\{number}
where {number} is a octal number with up to 3 digits specifying the character code.
Assignments and Operators
A "=" is used to assign a value to a Symbol.
Lexp_frame = 8
This is equivalent to the "equ" directive other assemblers use.
GAS supports addition (+), subtraction (-), multiplication(*), division (/), right shift (>), left shift (<), and (&), or (|), not (!), xor (^) and modulo (%) in expressions. The order of precedence is
          Rank    Examples
lowest   0       operand, (expression)
             1       + -
             2       & ^ ! |
             3       * / % < >
Parentheses are used to coerce the order of evaluation.
Segments, Location Counters and Labels
A program written in assembler language may be broken into three different segments; the TEXT, DATA and BSS sections. Pseudo opcodes are used to switch between the sections. The assembler maintains a location counter for each segment. When a label is used in the assembler input, it is assigned the current value of the active location counter. The location counter is incremented with every byte, that the assembler outputs. GAS actually allows you to have more than one TEXT or DATA segment. This is so to ease code generation by high level compilers.  The assembler concatenates the different sections in the end to form continuous regions of TEXT and/or DATA. When you do assembly programming by hand you would stick to the pseudo opcodes ".text" or ".data", which use text or data segment with number 0 by default.
Types
Symbol and Labels can be of one of three type. A Symbol is
absolute
; when it's values is known at assembly time. A assignment like "Lexp_frame = 8" gives the symbol "Lexp_frame" the absolute value 8. A symbol or label, which contains an offset from the beginning of a section, is called "relocatable". The actual value of this symbol can only be determined after the linking process or when the program is running in memory. The third type of symbols are
undefined externals
.  The actual value of this symbol is defined in an other program.
When different types of symbols are combined to form expressions the following rules apply: ("abs" = absolute, "rel" = relocatable, "ext" = undefined external)
abs + abs => abs
abs + rel = rel + abs => rel
abs + ext = ext + abs => ext
abs - abs => abs
rel - abs => rel
ext - abs => ext
rel - rel => abs
(makes only sense, when both relocatable expression are relative to same segment)
All other possible operators are only useful to form expressions with
absolute
 values or symbols.
Supported Pseudo Opcodes (Directives)
All pseudo opcodes start with a ".". They are followed by 0, 1 or more expressions separated by commas (depending on the directive). The following table omits the pseudo opcodes, which include special information for debugging purposes (for GDB).
.abort
aborts the assembly on the point.
.align {integer}
aligns the current segment in size to {integer} power of 2. The maximum value of {integer} is 15. The lines
.text
some code ...
.align 10               | 2^10 = 1024
.data
some more code ...
.align 10               | 2^10 = 1024
will create text and data sections, which both have the size 1024, although the actual code, that goes into the sections may be smaller.
.ascii {string}[,{string},....]
includes the {string}('s) in the assembly output.
.asciz {string}[,{string},...]
This directive is the same as above, but additionally appends a "\0" character to the string.
.byte {expr}[,{expr},...]
puts consecutive bytes with value {expr} into the output.
.comm {identifier},{integer}
creates a common area of {integer} bytes in the current segment, which is referenced by {identifier}. The {identifier} is visible from the outside of the module. It can therefore be used to resolve external reference from other modules.
.data [{integer}]
switches to DATA section {integer}. If {integer} is omitted, data section 0 is selected.
.desc
Whatsit good for ???
.double {double}[,{double},...]
puts consecutive doubles with value {double} into the output.
.even
sets the location counter of the current segment to the next even value.
.file
.line
If a file is assembled, which was generated by a compiler or preprocessed by the C preprocessor, the input may contain lines like "# 132 stdio.h".  These lines are change by the assembler to the form
.line 132
.file stdio.h
.fill {count},{size},{expr}
puts {count} areas with {size} into the output. Each area contains the value {expr}.  {size} may be an even number up to or equal to 8. The line
.fill 3, 4, 0xa5a
would put the following byte sequence in the output ("|" is only used to mark the size of the area.)
00 00 0a 5a | 00 00 0a 5a | 00 00 0a 5a
.float {float}[,{float},...]
puts consecutive floats with value {float} into the output.
.globl {identifier}[,{identifier},...]
When labels or identifiers are assigned, they are only locally defined.  The ".globl" directive gives {identifier} external scope. The label can therefore be used to resolve external references from other modules.  {identifier} don't have to be assigned in the current module, but can be defined in another module.
.int {expr}[,{expr},...]
puts consecutive integers (32 bit) with value {expr} into the output.
.lcomm {identifier},{integer}
is basically the same as ".comm", except that area is allocated in the BSS segment. The scope of {identifier} is only local (only  visible in the module, where it is defined).
.long {expr}[,{expr},...]
same as "int".
.lsym {identifier},{expr}
sets the local {identifier} to the value of {expr}. The {identifier} is referenced by preceding it with a "L".  ("L{identifier}) (When I tried this, the linker threw a bomb. Trying again crashed the system.)
.octa
Whatsit good for ???
.org {expr}
sets the location counter of the current segment to {expr}.
.quad
Whatsit good for ???
.set {identifier},{expr}
sets {identifier} to the value of {expr}. If {identifier} is not explicitly marked external by the ".globl" directive, it has only local scope.
.short {expr}[,{expr},...]
puts consecutive shorts (16 bit) with value {expr} into the output.
.space {count}, {expr}
puts {count} consecutive number of bytes with value {expr} into the output. The line
.space 5,3
is equivalent to
.byte 3, 3, 3, 3, 3
The "space" directive is a special form of the "fill" directive.
.text [{integer}]
switches to TEXT section {integer}. If {integer} is omitted, text section 0 is selected.
.word {expr}[,{expr},...]
same as ".short".
The Utilities
This chapter describes the programs, which don't actually convert the source code into object code, but instead combine several object code modules to a runnable program or an object code library. Other programs can be used to print symbol information from either the object code or the executable. The last group of utility programs modify the executables in terms of memory usage and startup time.
The Linker ("gcc-ld.ttp")
A linker combines several object modules and extracts modules from a library to produce a runnable program. During this process all undefined symbol references are resolved. Additionally all sections from the object modules, which belong to either the TEXT, DATA or BSS are moved to the correct program segment. For example, all areas of all the object code modules, which have the type TEXT, are moved to form one large TEXT section. The same applies to the DATA and BSS sections.
For the most time you don't have invoke the linker explicitly. The compiler driver does the job for you. But in case you have to, the general syntax is:
gcc-ld [{options}] $GNULIB\crt0.o {file}.o -l{library}
The above syntax assumes, that the executable is produced from C source code, which normally makes is necessary to link a startup module and a library. If an executable from a self contained assembler text is to be created, the startup module "crt0.o" and the library might be missing.  "gcc-ld.ttp" creates a file "a.out" by default. The linker can also append a DRI compatible or an extended symbol table to the executable.
"gcc-ld.ttp" supports the following command line options.
-f{load flags}
Set the program load flags to {load flags}. The default program load flags is 7 (TT ram, fastload).
-h{altheap size}
Set the minalt size in the executable header to {altheap size}.  The default value is zero. Remember that value is specified in 128k units. What this means is (quoting mintsrc/mem.c): If (flags & F_ALTLOAD == 1), then we might decide to load in alternate RAM if enough is available. "enough" is: if more alt ram than ST ram, load there; otherwise, if more than (minalt+1)*128K alt ram available for heap space, load in alt ram ("minalt" is the high byte of flags).
-l{library}
Search {library} to satisfy unresolved references. The environment variable "GNULIB" is used to locate the library.  "GNULIB" contains a "," or ";" separated list of paths, each path without a trailing slash or backslash.
-L{directory}
Includes {directory} in the search path to locate a library.
During the linking process extensive information about the encountered symbols is displayed.
Instead of the standard DRI compatible symbol table, an extended symbol table is written, which allows symbol names to be up to 22 characters long. Most of the other utility programs have been updated to work with this format. The most benefit you get with "gprof.ttp" and "szadb" (the adb-like debugger, originally written for the Sozobon C compiler by Johann Rueg and Don Dugger and later significantly improved by Michal Jaegermann).
-o{filename}
The resulting output of the linking process is written to {filename} instead to "a.out".
prevents the linker from attaching a symbol table to the executable.
During the linking process the files loaded and the modules extracted from a library are displayed.
This option discards all local symbols from the DRI symbol table. All global symbols are left in place.
sym-ld.ttp
"sym-ld.ttp" is a special version of the linker. His sole purpose is to create a special symbol file used by the GNU debugger. The following example show the usage. ("$" is the prompt of a CLI, "*" is the GDB prompt, "#" marks a comment)
$ gcc -c -g foo.c      # compile "foo.c"
$ gcc -o foo.prg foo.o -lgnu # link with normal "gcc-ld.ttp"
$ sym-ld -o foo.sym $(GNULIB)\crt0.o foo.o -lgnu
                       # (or -lgnu16 if you use -mshort)
                       # link with "sym-ld.ttp" to get symbol file
$ gdb
* exec-file foo.prg    # executable ("gcc-ld.ttp" linked Atari executable)
* symbol-file foo.sym  # symbols file ("sym-ld.ttp -o" linked)
* run
* <start doing gdb commands here>
$                      # back
  Note the line in the example, where "sym-ld.ttp" is invoked. A library "gnugdb.olb" is used to create the symbol file. This is just like the normal library "gnu.olb" except, that is was compiled with the "-g" option. If you don't have this library, use the normal library ("-lgnu"). In this case you can't single step through library functions at the source level. Also note, that "sym-ld.ttp" is invoked without the "-r" option. This option was only necessary for some very early versions of "gdb".
  For a bit more detailed info about debugging with "gdb" turn to chapter
Debugging
The Archiver "gcc-ar.ttp"
The archivers main purpose is to make things in programming life easier. The archiver combines several object modules into one large library. At a later time the linker will then retrieve the modules needed to resolve all references. Without the library you would have to supply all modules by hand on the command line or the linker would have to search through all the files to resolve the references (The library "gnu.olb" contains around 150 modules).
The general syntax for invoking "gcc-ar.ttp" is:
gcc-ar {option} [{position}] {library} [{module}]
The {option} specifies the action to be taken on the {library} or a {module} of that {library}.  {option} also includes modifiers for the action. The optional {position} argument is a member of the {library}. It is used, to mark a specific position in the {library}; an "add" operation would than place a new module before or after that {position}. The next argument specifies the library. The recommended naming convention for the creation of a new libraries is {library}.olb. If you don't use this convention, the compiler driver "gcc.ttp" will have trouble finding them.  {module} is usually an object code file generated by the compiler.
"gcc-ar.ttp" supports the following command line options. If you don't use a {position} the named module is appended or moved to the end of the library
The "add", "replace" or "move" operation should place the "module"
after
 "position".
The "add", "replace" or "move" operation should place the "module"
before
 "position".
If the specified "library" does not exist, it is silently created. Without this option "gcc-ar.ttp" would give you a notice, that it created a new library.
deletes "module" from the "library".
This is the same as option "b".
This option is ignored. (Why is there in the first place ??)
Move a member around inside the library.
preserves the modification time of a module, that is extracted from the library.
This option pipes the specified "module" directly to "<stdout>".
A quick append is performed.
causes "module" to be replaced. If the named module is not already present, it is appended. This is also the default action, when no "option" is given.
creates special member in the library called "__.SYMDEF", which contains a directory of the external names defined by all the other members.
lists the members, that are currently in the "library". If the option "v" is also given, additional information about file permissions, user- and group-id's and last modification date of the members are displayed. Of course, file permissions and user- and group-id's don't make much sense on the Atari ST.
If this option is given, an existing module in the library is only replaced, if the modification time of the new module is newer than the modification time of the one already in the library.
gives you some additional information depending on the operation, that currently performed.
Extract "module" from the "library".
Listing Symbols
There are two programs available for printing symbols; each for symbols of a different kind.  "gcc-nm.ttp" list symbols in GNU object files and object libraries.  "cnm.ttp" lists symbols from a DRI compatible or extended symbol table attached to an executable.
gcc-nm.ttp
The output of  "gcc-nm.ttp" looks like the following sample:
00000870 b _Lbss
         U _alloca
000003b4 t _glob_dir_to_array
00000532 T _glob_filename
00000248 T _glob_vector
         U _malloc
0000086c D _noglob_dot_filenames
         U _opendir
         U _readdir
00000000 t gcc_compiled.
The first column displays the relative address of that symbol in the object file. If the symbol has the type "U" (undefined external) the space in left blank. The next column shows the type of the symbol. In general, symbols, which have an external scope (visible for other object module) are marked with an uppercase letter. Symbols, which are local to the object file are marked with lowercase letters. The following letters are possible:
marks variables, which are defined in that source module, but not initialized. A declaration like
int variable;
would create a line marked with a "C". The first column would  show the size of that variable in bytes instead of the relative address in the object module.
Variables, which are declared with
static int variable;
are displayed with a "b".
marks variables, which are initialized at declaration time. A declaration like
int variable = 1;
would show as a line with a "D" in it.
Variables, which are initialized at declaration time declared are displayed with a "d". A declaration like
static int variable = 1;
would create a line marked with a "d".
mark text (in other words: actual program code). Functions in your C source, which have the storage class "static", would be displayed with a "t". All other functions in that source module, which are visible to other modules, would show up with a "T".
All functions, which are defined in other modules and referenced in this module, are displayed with a "U".
The last column shows the symbol name.
"gcc-nm.ttp" supports the following command line options.
In case a file is compiled with the "-g" or "-gg" option, special information for debugging purposes is included in the object code. This information is listed by supplying the "-a" option.
This option restricts the output to include only symbols, which have an external scope.
Without any options the output is sorted in ascii order. By supplying the "-n", the listing is sorted in numerical order by the addresses in first column.
If this option is given, every output line is preceded by a filename in the form "file:", naming the file in which the symbol appears. If the file to be listed, is an archive, the line begins in the form "library(member):".
The symbols are listed in the order as they appear in the object code module.
The output is sorted in reverse ascii order.
Archives may contain a special member called "__.SYMDEF". Don't ask me about it purpose. Anyway, using this option show the content of this member.
Only undefined symbols are listed.
cnm.ttp
"cnm.ttp" prints the symbols which are attached to an executable.
Modifying the Executables
The programs, which are described in the following sections can be used to modify an already existing executable, but this only works under the assumption, that the symbol table is still attached to the executable. So, if you want to modify the memory usage of a program at a later time, you should keep the unstripped executables around or use the command "xstrip.ttp" and keep only the "_stksize" symbol.
fixstk.ttp
"fixstk.ttp" is used to modify the current stacksize of an executable.  It does this by looking up the symbol "_stksize" in the symbol table portion of the file and than changes the values of the location where "_stksize" points to. The usage is:
fixstk {size} [{filename}]
{size} is the stacksize in Bytes, KBytes or MBytes. To specify {size} in Kbytes or Mbytes, append a "K" or a "M" to the integer number.
For dumping applications like Scott Kolodzieski's port of GNU Emacs 18.57 "fixstk.ttp" looks up the symbol "_initial_stack" instead of "_stksize".
fixstk 128K gcc-as.ttp
sets the stacksize of "gcc-as.ttp" to 128 Kbytes.
toglclr.ttp
toglclr [-fload] [-frun] [-fram] {files} ...
-fload
Toggle the "fast load" flag.
-frun
Toggle the "fast run" flag.
-fram
Toggle the "fast ram malloc" flag.
  If TOS launches an application, it clears all memory starting from the BSS section to the end of the TPA. With earlier TOS versions (pre TOS 1.4) this could take quite a considerable amount of time. The clearing algorithm was improved during the different TOS releases, but it is still used, although
 of the existing programs don't need a cleared memory. Well, most is not all; therefore for compatibility sake the feature will stay in place.
  With TOS 1.4 you can keep the GEMDOS loader from clearing all memory.  The long word with offset 0x16 in the program header is used to determine whether the memory should be cleared or not. Setting the bit 0 of this longword to 1 prevents the loader from clearing all memory.  "toglclr.ttp" serves exactly that purpose, namely toggling this long word.
  TOS 2.x and 3.x gave another two bits in the above mentioned longword a meaning. The "fast run" bit 1 is used to determine, if a program should be started in ordinary ST-ram (bit 1 = 0) or in alternate ram. In
case of the TT or the SST68030 from Dave Small, this is ram which is not slowed down by any video hardware.
  The "fast ram malloc" bit 2 determines, if any subsequent malloc's, which a program might do, should be satisfied from slow ST-ram (bit 2 = 0) or from alterate ram. All these flags have been introduced to increase compatibility between the different TOS versions.
xstrip.ttp
  "xstrip.ttp" removes the symbol table from a TOS executable file.  The default behaviour, which is to completely remove the symbol table, may be modified by specifying additional command line optione. The systax for the xstrip command is
xstrip [-a] [-g] [-k] [-l {names}] {files} ...
Really remove all of the symbol table. Leave nothing.
This option causes "xstrip.ttp" to keep all global symbols.
keeps the "_stksize" symbol, so that the stack size can be adjusted even for a nearly-stripped GCC produced executables.
-l {names}
keeps all symbols listed in a file {names} (one symbol per line).
Both "-k" and "-l" options convert the extended symbols into regular ones (DRI compatible).
Getting Information about Executables
printstk.ttp
"printstk.ttp" works basically the same way as "fixstk.ttp", but displays the current value at the location "_stksize" or "_initial_stack". The usage is:
printstk [{filename}]
If {filename} is not specified it defaults to ".\gcc-cc1.ttp".  If "printstk.ttp" is used on some of the executables of the GCC distribution, you should see a value of "-1", which means that all available memory is used by the program (at least for the programs "gcc-cpp.ttp" and "gcc-cc1.ttp").
size68.ttp
  "size68.ttp" is used to print information, which is found in the the header of an executable program file. A sample output is shown in the following lines.
c:\ => size68 temacs
temacs:
        text size       245884
        data size       160604
        bss size        11552
        symbol size     36274
        File is relocatable
        BSS and high mem cleared on startup
  The value of "text size" is the actual size of the program code; the TEXT segment. The value of "data size" gives the size of initialized data; the DATA segment. For example, if you define a variable "char array[10] = "foobar";", the string "foobar" is moved to the data segment during the linking process. The value of "bss size" is the size of the BSS segment. If you define a global variable "char array[10];", this variable "array" would end up the BSS segment. The BSS segment is initialized to zero from the GEMDOS loader, when the program is loaded into memory. The memory usage during the programs runtime can't simply be calculated by adding the three values, since this doesn't take into account the memory, which might be dynamically allocated.
  The value of "symbol table" is the size of the symbol table, which is appended to the three segments. The symbol table is only used, when the program is invoked under the control of a debugger. The symbol table doesn't use up any memory, when the program is launched from the desktop or a CLI. The next line says, that the program file is relocatable. As far as I know is every program file relocatable on the
ST. The last line indicates, that the BSS section and the all available memory ("high mem") is cleared upon startup. On systems with lots of memory, this can take quite a bit of time. You can keep the GEMDOS loader from clearing all memory by toggling a bit in the header. See "toglclr.ttp" for more info.
Debugging Programs
  In general, you have two choices for debugging; machine and source level debugging. Most of the time you will prefer the source level debugging.
This chapter is not ready yet. If you have some ideas, what should go into this section, please tell me.
Swiss 721